home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / program / svgakt50.zip / DOC / SVGAKIT / SVGAKIT.DOC < prev    next >
Text File  |  1994-08-23  |  13KB  |  294 lines
  1.  
  2.                             The SuperVGA Kit
  3.                             ----------------
  4.  
  5.                                Version 5.0
  6.  
  7.                               22 August 1994
  8.  
  9.  
  10. The SuperVGA Kit is a set of routines for working with SuperVGA
  11. video cards that have a VESA VBE compliant Video BIOS. This library was
  12. an offshoot from the development of the Universal VESA VBE, which is an
  13. installable TSR to provide VESA VBE video BIOS extensions for most
  14. SuperVGA cards. It is intended to show how to program the SuperVGA
  15. cards through the VESA VBE and uses some of the more powerful features
  16. that the latest standard include in your own software.
  17.  
  18. This library supports many of the extended features of today's SuperVGA
  19. adapters, such as being able to separately set the read and write banks
  20. and support for extended page flipping. This is all done via the
  21. standard VESA VBE programming interface.
  22.  
  23. NOTE: All source code is formatted with 4 space tabs, including the
  24.       assembly language source.
  25.  
  26. NOTE: This library has '386 specific code in it, so it will _not_ work
  27.       with machines without a '286 or lower processor. Some of the code
  28.       such as the screen clearing code etc uses fast 32 bit string
  29.       instructions to run at full speed on new VESA VLB Local Bus
  30.       video cards.
  31.  
  32. Using it in your own programs
  33. -----------------------------
  34.  
  35. The SuperVGA test programs all call upon a single C library to access the
  36. SuperVGA using the VESA VBE programming interface. You can use this
  37. same library to provide SuperVGA support in your own applications, or
  38. you can take the source code for the library as a starting point and
  39. expanding on it from there.
  40.  
  41. Assembling the source files
  42. ---------------------------
  43.  
  44. All of the assembler source files have to be assembled with Borland's TASM,
  45. since they are written using TASM's IDEAL mode. If you do not have TASM,
  46. you can simply link with the pre-assembled object files provided.
  47.  
  48. Test programs
  49. -------------
  50.  
  51. The library now has only one single test program, that presents a set of
  52. menus for testing all of the available video modes that the library
  53. supports (and your hardware supports).
  54.  
  55. Note that the test program requires a VESA VBE compliant SuperVGA in
  56. order to run, so if your video card does not have the VESA VBE in the BIOS,
  57. then you will need to install the Universal VESA VBE before running it.
  58.  
  59. VBETest
  60. -------
  61.  
  62. The SuperVGA Kit also includes the executable and source code for the
  63. VBETEST.EXE program. This program is a stress test program for the VESA
  64. VBE interface to check the BIOS of your video card (or the installed version
  65. of UniVBE if you are using this) for conformance. It fully tests all the
  66. standard and advanced functions of the VESA VBE 1.2 interface, and will
  67. report any errors that it detects to the VBETEST.LOG file.
  68.  
  69. Unfortunately many video BIOS'es pass the conformance test, however the results
  70. that are displayed visually on the screen (such as when doing wide virtual
  71. screens and scrolling) are not correct. If this is the case then you can
  72. consider that the BIOS has failed the conformance test. If you have a BIOS
  73. that does not pass the test, you might like to contact your video card's
  74. manufacturer and report the problems to them.
  75.  
  76. PM/Lite library
  77. ---------------
  78.  
  79. The SuperVGA Kit uses the PM/Lite library, which should also have come
  80. as pre-compiled library files in the same archive. If you wish to compile
  81. it up for a different extender, you will need to obtain the source code
  82. archive (see the file INSTALL.ME for details).
  83.  
  84. Global Variables Reference
  85. --------------------------
  86.  
  87. int     maxx,maxy;          Maximum device coordinate values (res-1)
  88. long    maxcolor,defcolor;  Maximum and default color values
  89. int     maxpage;            Maximum video page number (numpages-1)
  90. int     bytesperline;       Bytes in a logical scanline
  91. int     bytesperpixel;      Bytes in a pixel (if > 1)
  92. bool    twobanks;           True if separate banks available
  93. int     memory;             Video memory available in Kb
  94. short   modeList[];         List of available video modes (USE THIS!)
  95. char    OEMString[];        OEM string from VBE
  96.  
  97. The following two globals are only valid if the enableSpecialFeatures
  98. flag is set to TRUE when initSuperVGA() is called.
  99.  
  100. bool    extendedflipping;   True if we have extended flipping
  101. bool    widedac;            True if wide dac is supported
  102.  
  103. The following globals defint the pixel format information, and is used by the
  104. rgbColor() routine to build the correct pixel for the current display mode.
  105. You can however use it yourself to build scanline information in the desired
  106. format if you need to optimise these routines for speed.
  107.  
  108. uchar   redMask,greenMask,blueMask;  Color channel mask values
  109. int     redPos,greenPos,bluePos;     Starting position of color channel bits
  110. int     redAdjust,greenAdjust;       Shift factors need to adjust to correct
  111. int     blueAdjust;                     postition in pixel image
  112.  
  113. Function Reference
  114. ------------------
  115.  
  116. int initSuperVGA(bool enableSpecialFeatures);
  117.  
  118.         Initialise the SuperVGA Kit. The enableSpecialFeatures flag is
  119.         used to enable the detection of the 8 bit wide RAMDAC and SuperVGA
  120.         page flipping. In order to detect this, a SuperVGA video mode must
  121.         be started, so the screen will be cleared. Leaving this flag
  122.         false will not change the current video mode.
  123.  
  124.         Returns the packed BCD version number for the VBE interface
  125.         detected, or 0 if none is present. For VBE 1.2 this is 0x102, for
  126.         VBE 2.0 this will be 0x200.
  127.  
  128. bool setSuperVGAMode(int mode);
  129.  
  130.         Set the specified video mode, given the internal VBE mode number.
  131.         DONT pass old style VBE mode numbers to this routine (ie: 0x101
  132.         for 640x480x256), although the will still work, the extensible
  133.         method is to search through the list of available video modes
  134.         for the one that has the desired resolution and color depth. This
  135.         will allow you code to work with all custom video resolutions
  136.         provided by different OEM VBE drivers (like UniVBE/Pro). Have a
  137.         look at the code in the HELLOVBE.C file that demonstrates how
  138.         to start any video mode given a user specified resolution.
  139.  
  140.         The display page is always cleared to black when this routine is
  141.         called.
  142.  
  143.         Returns FALSE is the mode could not be set correctly.
  144.  
  145. void restoreMode(void);
  146.  
  147.         Restores the previous video mode active befor the setSuperVGAMode
  148.         routine was called. Also correctly restores the VGA 50 line mode
  149.         if it was previously active.
  150.  
  151. bool getSuperVGAModeInfo(int mode,int *xres,int *yres,int *bytesperline,
  152.     int *bitsperpixel,int *memmodel,int *maxpage,long *pagesize);
  153.  
  154.         Returns the video mode information for the specified VBE internal
  155.         video mode number. The mode number must be valid, or this routine
  156.         will return FALSE. Check the modeList[] array which contains the
  157.         list of available video modes that you can use.
  158.  
  159. bool setSuperVGADisplayStart(int x,int y);
  160.  
  161.         Sets the CRTC display starting address to the specified value. You
  162.         can use this routine to implement hardware scrolling (if you wish
  163.         to set up a wide virtual screen, you will need to call VBE function
  164.         07h yourself, as we dont currently have this function implemented
  165.         in the SuperVGA Kit).
  166.  
  167.         To perform double buffered animation, use the setActivePage() and
  168.         setVisualPage() routines instead.
  169.  
  170.         Returns FALSE if the value could not be set.
  171.  
  172. bool set8BitPalette(void);
  173.  
  174.         This function enables the 8 bit wide palette if available and
  175.         returns TRUE. If an 8 bit wide palette is not available, this
  176.         routine returns FALSE and the palette width is unchanged.
  177.  
  178. bool set6BitPalette(void);
  179.  
  180.         This function restores the default VGA style 6 bit palette.
  181.  
  182. void setPalette(int start, int num, palette *palbuf);
  183.  
  184.         This function set the specified palette entries, by calling the
  185.         video BIOS. Eventually this will become a native VBE function
  186.         in VBE 2.0, and will eliminate all the problems associated with
  187.         snow.
  188.  
  189.         The buffer is expected to be in the correct format, which will
  190.         be an array of 'palette' structures. If the palette is currently
  191.         in the default 6 bit VGA mode, this routine expects the values to
  192.         be 6 bits wide. If it is in an 8 bit palette mode, then the values
  193.         should be 8 bits wide (and hence you will need to do the
  194.         conversion yourself).
  195.  
  196. void getPalette(int start, int num, palette *palbuf);
  197.  
  198.         This function reads the current value of the paletet and stores
  199.         it in the buffer.
  200.  
  201. long rgbColor(uchar r,uchar g,uchar b);
  202.  
  203.         Packs a set of RGB values into a color value for passing to the
  204.         primitive drawing routines that is appropriate for the current
  205.         video mode. This routine is intended to work with RGB video modes
  206.         such as the 15, 16, 24 and 32 bits per pixel modes (in 8 bit modes
  207.         it will packed it into a simple 2:3:2 style pixel, so you can set
  208.         up your own pseudo RGB palette if you so desire).
  209.  
  210.         You should use this routine to convert all color values to ensure
  211.         that they work correctly on the different types of direct color
  212.         video modes available.
  213.  
  214. void writeText(int x,int y,char *str,long color);
  215.  
  216.         Writes the text sting at the location x,y in the standard VGA
  217.         8x16 VGA font, and the specified color. The background between
  218.         the text is not erased.
  219.  
  220. void setActivePage(int page);
  221.  
  222.         Sets the currently active video page for output. Used to implement
  223.         SuperVGA double buffering for smooth animation.
  224.  
  225. void setVisualPage(int page);
  226.  
  227.         Sets the currently visible display page. Used to implement SuperVGA
  228.         double buffering for smooth animation.
  229.  
  230. void setBank(int bank);
  231.  
  232.         Set the current read/write bank values to the same location.
  233.  
  234. void setReadBank(int bank);
  235.  
  236.         Sets the read bank value to a different location. If you wish to
  237.         use separate read/write banks, you will need to first set the
  238.         read/write banks to the write bank location with the setBank()
  239.         routine above, then call this routine to change the read bank
  240.         to a different location.
  241.  
  242. void putPixel(int x,int y,long color);
  243.  
  244.         Plots a pixel at the specified (x,y) location in the specified
  245.         color. The color value MUST be in the correct format for the
  246.         current video mode (use rgbColor() to pack HiColor and TrueColor
  247.         RGB values). The pixel is plotted on the currently active
  248.         display page (which may possibly be hidden from view).
  249.  
  250. void clear(long color);
  251.  
  252.         Clears the currently active display page to the specified color.
  253.         The color value MUST be in the correct format for the current video
  254.         mode (use rgbColor() to pack HiColor and TrueColor RGB values).
  255.  
  256. void line(int x1,int y1,int x2,int y2,long color);
  257.  
  258.         Draws a line from the point (x1,y1) to (x2,y2) in the specified
  259.         color. The color value MUST be in the correct format for the
  260.         current video mode (use rgbColor() to pack HiColor and TrueColor
  261.         RGB values). The line is drawn on the currently active
  262.         display page (which may possibly be hidden from view).
  263.  
  264. Where to get the latest version
  265. -------------------------------
  266.  
  267. You can probably get the latest version of the package from Simtel20 or
  268. garbo (and their mirrors):
  269.  
  270.     oak.oakland.edu:    pub/msdos/graphics/svgakt??.zip
  271.     garbo.uwasa.fi:     pc/graphics/svgakt??.zip
  272.  
  273. If you have access to CompuServe, you can download the file from the
  274. IBMPRO VESA file library (12) as the file svkt??.zip (CompuServe has
  275. restrictive file naming conventions).
  276.  
  277. Corrections, updates and queries
  278. --------------------------------
  279.  
  280. If you have any corrections or updates to the code in this package, or
  281. you have any questions you would like asked, feel free to contact me
  282. through one of the following methods.
  283.  
  284. Internet:       rcskb@minyos.xx.rmit.edu.au
  285. Compuserve:     100237,2213
  286. Fax:            +61 3 690 2137
  287.  
  288. Snail Mail:     Kendall Bennett
  289.                 SciTech Software Australia
  290.                 Unit 5, 106 Southbank Boulevard
  291.                 South Melbourne 3205
  292.                 AUSTRALIA
  293.  
  294.